fix(spec): the defaultValue literal gate prescribes the key rename, not a missing-member type error - #16409

Fixes #16077

checkLiteralDefaultValue — the shared core of the FieldSchema.defaultValue gate (#7127) and the ActionParamSchema.defaultValue gate (#6970) — read a value-contract rejection positionally, result.error.issues[0]. zod reports per-member issues before the object-level unrecognized_keys one, so when an author RENAMED a key the message naming the rename sorted last and was discarded, and the author was handed a missing-member type error about a member they never wrote.

The gate now prefers the unrecognized_keys issue when the rejection carries one — the same shape #15490 landed on the stored-value path, implemented separately here because packages/spec is upstream of objectql and cannot import that helper.

Reproduced on current main before touching anything

The card's three reproductions were measured at c463d03e0. Re-measured on origin/main at de75e407e5 rather than inherited — all three still hold, byte-identical to the card:

The third row is the point: which diagnosis an author got depended on whether some unrelated member happened to also be wrong. That asymmetry is what this removes.

Prerequisite 1 — the 16-class sweep, re-run ON THIS FUNCTION

#15490's sweep was taken on the record-validator.ts path; that it carries over here was an inference. Measured here instead, over every class valueSchemaFor(def, 'stored') covers, at BOTH arities ({type} and {type, multiple: true}), probing each with object literals carrying undeclared keys:

2 of 16 — location and address, the only two backed by a strictObject. The preference is a no-op for the other fourteen, measured on this function rather than carried over. A pin holding that no-op ships with the change.

Prerequisite 2 — callers and pins on the current detail text

Callers of checkLiteralDefaultValue, from grep -rn "checkLiteralDefaultValue" over the whole tree excluding node_modules and dist:

• packages/spec/src/ui/action.zod.ts:500 — composes verdict.detail into the action-param refusal.
• packages/spec/src/ui/action.zod.ts:510 — arity retry; reads .ok only, never .detail.
• packages/spec/src/data/field.zod.ts:2070 — composes verdict.detail into the field refusal.
• packages/spec/src/data/default-value-shape.test.ts — the unit test.
• Zero callers outside this repo's packages/spec. Checked objectui at 51a402f: 0 hits.

Assertions pinning the current text: none, and the searches that returned that zero were lit first.

• default-value-shape.test.ts:98 pins detail for a datetime (toContain('ISO-8601 instant')) — class 5, where unrecognized_keys is unreachable, so unmoved.
• field-default-value.test.ts already carried an address and a location rejection row, but both are the LUCKY half: their other members are well-typed, so nothing sorted ahead and the rename surfaced by accident. Both still pass.
• Positive control for the test-tree search: grep -rn -F "ISO-8601 instant" over *.ts/*.tsx returns 16 hits including default-value-shape.test.ts:98 — the search reaches the test tree and can return a hit.
• Positive control for the message-text search: grep -rn -F "Unrecognized key(s) on this address value" over *.ts,*.tsx,*.md,*.mdx,*.json,*.snap returns 1 hit — the search reaches those file types.
• Positive control for the objectui search: grep -rln "LocationField" returns 17 files there.

One trap worth recording: the first pass searched for the composed phrase cannot satisfy this field's own stored value contract and got zero — because the producer splits it across template-literal concatenation lines, so it exists on no single line. Zero from a search whose control had not been lit is not a reading; the shorter single-line-safe phrases above are.

Clause 2 — I read it as NO, same as the dispatch

The mechanical floor in references/contract-review.md is a new exported symbol, or a new key on a published payload. This diff has neither:

• actionableValueIssueMessage is module-local, not exported.
• LiteralDefaultValueVerdict keeps exactly { ok, detail? } — no new key, no type change.
• Mechanically confirmed against the generated export ledgers: check:api-surface exit 0 and check:export-origins exit 0 ("5277 exports across 17 entry points resolve exactly as recorded"), with git status clean after the build, so neither ledger moved.

What moves is which of several ALREADY-reachable messages detail carries. The declared meaning — "the 'why' a refusal carries verbatim" — does not move; the implementation is brought into line with it. That is the triage seat's own 声明 ≠ 交付 framing. No verdict moves either: exactly the same defaults are accepted and refused.

The one doc edit is the incidental half of the same TSDoc line, "First issue message", which described the mechanism that was wrong. The load-bearing half is kept verbatim.

Tests

Six new pins, each asserting BOTH halves — the prescription is present AND the half that was shown instead is gone. Without the second half a pin cannot see a regression back to the positional read.

• default-value-shape.test.ts — the core: missing-member case (location), wrong-typed-member case (address), the asymmetry-is-gone pin holding the lucky and unlucky cases equal, and the no-op pin for a class that cannot emit unrecognized_keys.
• field-default-value.test.ts — two rows on the existing case table, which grew a notContains column.
• action-param-default-value.test.ts — one pin, because that consumer composes detail into its own message: a core fix that never reached the composed text would be invisible to a core-only pin.

Ablation. From the committed implementation, the call site was mutated back to the positional read, proven on disk (anchor counts 1 to 0 for the new spelling and 0 to 1 for the old; blob hash differs from the HEAD blob), the three files re-run, then restored via git checkout HEAD -- path and the restore proven by blob-hash equality plus an empty git diff HEAD. Result: exactly the 6 new pins fail, the other 93 in those files pass. Direction: turned red, as predicted. No build was needed — the pins import the subject by relative path within its own package, so vitest reads src/, not dist/.

Verification

Every verdict below is the gate's own printed line with its exit code captured before any pipe.

• pnpm --filter @objectstack/spec test — exit 0. Test Files 481 passed | 1 skipped (482), Tests 13107 passed | 1 skipped (13108).
• pnpm --filter @objectstack/spec typecheck — exit 0, all three legs (tsc --noEmit, check:scripts-typecheck, check:test-typecheck). The test layer is MEASURED, not assumed: tsc -p tsconfig.test.json --listFiles puts all four changed files in a 2270-file program, and the debt ledger held at 54 file(s) / 261 error(s) / 145 pinned signature(s) unchanged.
• Gate families derived mechanically with scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack rather than from the dispatch list: 73 families. 71 ran green.
• pnpm lint (eslint . --no-inline-config, the whole repo — no narrowing) — exit 0 at 395a57c3d.
• Control-character self-scan over all five changed files: 0 hits, with a positive control lit on a planted BEL byte. pnpm check:nul-bytes exit 0.

NOT MEASURED locally — 2 of 73, handed to CI, reconciled with dispatch-gates.mjs --ran which named exactly these two:

• pnpm check:dual-build-cjs-loads — exit 3, PREREQUISITE NOT MET, needs all 79 packages built.
• pnpm check:type-check-debt — exit 3, PREREQUISITE NOT MET, needs the full workspace closure built.

Both print "This is NOT a pass and NOT a finding: nothing was measured." A whole-workspace build is the CI farm's run, not a foreground one. Reported as unmeasured, not as green.

Six gates first returned exit 1 or 3 purely because packages/spec was unbuilt (check:api-surface, check:dual-source-exports, check:browser-reachable-entries, check:entry-nameability, check:exported-any, check:doc-formula-expressions). Those are PREREQUISITE NOT MET, not findings; after turbo run build --filter=@objectstack/spec --filter=@objectstack/formula --filter=@objectstack/lint all six re-ran green, and those greens are what the 71 counts.

Scope

The stored-value scan (record-validator.ts, #15490) is deliberately untouched — a different surface with a different audience, as the card and the triage seat both drew it. No adjacent defects were found to file.

⛔ Draft on purpose. Not for ready, not for the queue — the PM's call after review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno

Generated by Claude Code